final_model: Joins ENM from several partitions, creating a model per...

Description Usage Arguments Value References See Also Examples

View source: R/final_model.R

Description

This function reads the models generated either by do_any or do_many (i.e. one model per partition per algorithm) and summarizes them into a final model for each species-algorithm combination. These final models may be created from the raw continuous models, the binary models or the "cut" models (see do_any). They may use all partitions or select only partitions with performance metrics above a defined value (parameters select_partitions, select_par and select_par_val). The function can also calculate weighted means of the partitions (selected or not) using a performance statistic (passed to argument weight_par). After selecting and/or weighing each partition, a series of output can be created, see which_models for details about the final outputs available. Uncertainty taken as ranges between partitions may also be calculated. Analogous to no silver bullets in correlative ecological niche modeling, no method for evaluating and selecting partitions is always better and these are only a subset of the possibilities. The user should choose how to create the final model based on their assumptions. We simply recommend to focus on statistical clarity rather than significance \insertCitedushoff_can_2019modleR.

Usage

1
2
3
4
5
6
7
final_model(species_name, algorithms = NULL, select_partitions = TRUE,
  select_par = "TSSmax", select_par_val = 0.7, weight_par = NULL,
  cut_level = c("spec_sens"), scale_models = TRUE,
  consensus_level = 0.5, models_dir = "./models",
  final_dir = "final_models", proj_dir = "present",
  which_models = c("raw_mean"), uncertainty = FALSE,
  write_final = TRUE, ...)

Arguments

species_name

A character string with the species name. Because species name will be used as a directory name, avoid non-ASCII characters, spaces and punctuation marks. Recommendation is to adopt "Genus_species" format. See names in example_occs as an example

algorithms

Character vector specifying which algorithms will be processed. Note that it can have length > 1, ex. c("bioclim", "rf"). Defaults to NULL: if no name is given it will process all algorithms present in the evaluation files

select_partitions

Logical. If TRUE only partitions above a particular threshold value are selected

select_par

Which performance statistic should be used to select the partitions. Defaults to NULL but either "AUC" or "TSSmax" can be used

select_par_val

Performance metric value to select partitions

weight_par

Which performance statistic should be used to weigh the partitions. Defaults to NULL but either c("AUC", "TSSmax") can be used

cut_level

A threshold that will be used to cut the raw mean models. Default is set to "spec_sens" but any dismo threshold (see function threshold) can be used: "kappa", "no_omission", "prevalence", "equal_sens_spec", "sensitivity"

scale_models

Logical. Whether input models should be scaled between 0 and 1

consensus_level

Which proportion of binary models will be kept when creating bin_consensus

models_dir

Character. Folder path where the input files are located

final_dir

Character. Name of the folder to save the output files. A subfolder will be created, defaults to "final_model"

proj_dir

Character. The name of the subfolder with the projection. Defaults to "present" but can be set according to the other projections (i.e. to execute the function in projected models)

which_models

Which final_model will be used? Currently it can be:

raw_mean

Continuous model generated by the mean of the raw models (scale from 0 to 1)

raw_mean_th

Cuts the raw_mean by the mean of the thresholds that maximize the selected evaluation metric (e.g. TSS (spec_sens) to make a binary model

raw_mean_cut

Recovers raw_mean values above the mean threshold that maximizes the selected evaluation metric (e.g. TSS (spec_sens) or other dismo thresholds). Generates a continuous model

bin_mean

The mean of the selected binary models. Generates a model in a discrete scale (0 to 1 in 1/n intervals where n is the number of retained models)

bin_consensus

The binary consensus from bin_mean. Parameter consensus_level must be defined, 0.5 means a majority consensus

cut_mean

The mean of the selected cut models. Values below the thresholds are down-weighted by zeros

uncertainty

Whether an uncertainty map, measured as range (max-min) should be calculated

write_final

Logical. If TRUE, writes png files of the final models

...

Other parameters from writeRaster, especially overwrite = TRUE, when needed

Value

Returns a data frame with final statistics of the partitions included in the final model

Writes on disk a set of ecological niche models (.tif files) in the final_dir subfolder

If write_final = TRUE writes .png figures in the final_dir subfolder

References

\insertAllCited

See Also

threshold in dismo package

writeRaster in raster package

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# run setup_sdmdata
sp <- names(example_occs)[1]
sp_coord <- example_occs[[1]]
sp_setup <- setup_sdmdata(species_name = sp,
                          occurrences = sp_coord,
                          predictors = example_vars)

# run do_any
sp_bioclim <- do_any(species_name = sp,
                     predictors = example_vars,
                     algorithm = "bioclim")

# run final_model
sp_final <- final_model(species_name = sp,
                        algorithms = "bioclim",
                        select_partitions = TRUE,
                        select_par = "TSSmax",
                        select_par_val = 0,
                        which_models = c("bin_consensus"),
                        consensus_level = 0.5,
                        overwrite = TRUE)

Model-R/modleR documentation built on Dec. 3, 2019, 4:54 p.m.