aohMixK: aohMixK: mapping the species' AOH by mixing data from EOO and...
In thaisdoria/habitaR: Tools for mapping the species’ area of habitat (AOH) from geospatial data

Description Usage Arguments Details Value Author(s) References See Also Examples

Based on a mix approach combining species' distribution models with the occurrences records, draws species' spatial-informed distribution (e.g. alpha hull) to correcting for over-prediction from modeling techniques (e.g. SDMs). It is develop by adapting the approach described in Kremen et al. (2008), so that the species' area of habitat (AOH) can be interpreted as the models corrected for over-prediction.

aohMixK(modSp = modSp, occ = occ, crs = NULL, distOcc = NULL,
threshold = 0.4, fraction = NULL, partCount = NULL, alphaIncrement = NULL,
buff = NULL,  continuous=TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = TRUE, validation = TRUE)

`modSp`	Species distribution derived from modelling techniques (eg. SDMs). It might correspond to: path for a folder with species distribution models files (.asc or .tif format). a list of 'RasterLayer' objects (see `readRas` to obtain such class of object). 'RasterLayer', 'RasterStack' or 'RasterBrick' objects.
`occ`	Occurrences records of the species (coordinates in decimal degrees). 'It might correspond to path for a folder with the species occurrences files (.csv format) a list of 'data.frames' with the occurrences from multiple species (see data examples) a list of of 'SpatialPoints' from multiple species (see data examples) 'spOcc' object corresponding to a list of 'SpatialPoints' from multiple species (see `readOcc` to obtain such object). NOTE: If path is provided, each .csv file should correspond to only one species and the file must be named with the corresponding species names. The files must have 3 columns identified as "species" (species names or other identification of taxa), "long" (longitude), "lat" (latitude). Longitude must be in a column before the latitude column.
`crs`	The Coordinate Reference System (CRS) specifing the projection and datum of dataset. Could be a CRS object or a character string. Only used if 'occ' not correspond to a object from 'SpatialPoints' class.
`distOcc`	A value corresponding to the minimum distance to consider two coordinates as not duplicate. Values up to this distance will correspond to duplicates and removed. Units of this value must be in km. Default is zero (i.e. only exactly coincindent coordinates will be removed). Optional and only used if 'occ' is a path for .csv files or a list of data.frames. If 'occ' correspond to 'SpatialPoints', this argument should be ignored (i.e., distOcc = NULL). For more details, see `remove.duplicates` in the sp package.
`threshold`	Numeric value (between 0 and 1)indicating the threshold of species'suitability habitat from models that will be used to filter the set of occurrences records and then construct the species alpha hull. From all occurrences, only those records coinciding with cells whose suitability values are equal or above this threshold will be used to build the alpha hull. If multiple species are considered, this object might correspond to: A general numeric value (e.g. 0.2, 0.6) to be applied for all species, or A data.frame with specific threshold values for each species. NOTE: Default is 0.40 (following Kremen et al. 2008). See details.
`fraction`	The minimum fraction of occurrences that must be included in polygon.
`partCount`	The maximum number of disjunct polygons that are allowed.
`alphaIncrement`	The amount to increase alpha with each iteration.
`buff`	A buffer distance in meters to increase boundaries of alpha hull. Default is zero (0).
`continuous`	(logical) Whether the output should continuous instead binary for the rasters. Default is `TRUE`
`progress`	(logical) A bar showing the progress of the function. Default is `TRUE`.
`removeTempFile`	(logical) Whether the temporary files generated in each iteration should be deleted. It is recommended if the user wants to analyse a high volume of data at the same time. Default is `TRUE`.
`saveRas`	(logical) Whether the output should be saved in the working directory as raster files (.asc format). Default is `FALSE`
`stack`	(logical) Whether the output mapsshould be returned as a stack of 'RasterLayer' files. Default is `TRUE`.
`validation`	(logical) Whether the output should also return a data.frame with the measures used to evaluate the model's performance. Default is `TRUE`

Species distribution models (SDMs) are corrected for over-prediction through an adapted approach presented by Kremen et al. (2008). From the SDMs and a specified threshold value, a distribution polygon is drawn based on alpha hull method. Only the occurrences records that are above the suitability threshold defined by threshold are used to construct alpha hull. By default, the threshold is 0.40 (following Kremen et al. 2008), but disctinct values can also be assigned by the user. For multiple-species analysis, specific threshold values can also be informed to be considered for each species.

By default, aohMixK returns a list with three elements:

A 'RasterStack' (if stack = TRUE) or list of 'RasterLayer' objects (if stack = FALSE) of maps representing the AOHs generated from correction for over-prediction of models.
A data.frame of species and the respective alpha values and number of occurrences (after the removal of duplicate coordinates) used to construct the alpha hull. If the conditions assigned by the user to build the alpha hulls cannot be satisfied, is returned the minimum convex hull (MCH) and the alpha value is identified as 'MCH'.
A data.frame of species and the respective measures relative to construction and evaluation of distribution maps obtained from the correction for over-prediction of modelS, as follow:
- CellsEOO - Alpha Hull size measured in number of cells
- CellsMOD - Model size measured in number of cells
- (MOD-EOO) - Difference, in number of cells, between the model and the alpha hull. This measure can be used to evaluate the performance of this analysis.
- DifSizes - A value representing how bigger is the EOO comparing with the MOD. This measure can be used to evaluate the performance of this analysis.
- Prop - Proportion of the EOO (AlphaHull) maintained in the corrected for over-prediction SDMs. This measure can be used to evaluate the performance of this analysis.

Thaís Dória & Daniel Gonçalves-Souza

1. Kremen, C., Cameron, A., Moilanen, A., Phillips, S. J., Thomas, C. D., Beentje, H., ... Zjhra, M. L. (2008). Aligning Conservation Priorities Across Taxa in Madagascar with High-Resolution Planning Tools. Science, 320(5873), 222-226.

The dynamic alpha hulls drawn from the sequentially increasing of alpha values are created with getDynamicAlphaHull from rangeBuilder package.

### Path for folder to models and occurrences as Input ###

## Not run: 

# Binary Output #
aohmixK_bin <- aohMixK (modSp = path_mod, occ = path_occ,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = FALSE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

# Continuous Output #

aohmixK_con <- aohMixK (modSp = path_mod, occ = path_occ,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)


## End(Not run)

### RasterLayer of models and DataFrame of occurrences as Input ###

# Binary Output #

aohmixK_bin <- aohMixK (modSp = sdm_plantRas5spp, occ = df_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = FALSE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

# Continuous Output #

aohmixK_con <- aohMixK (modSp = sdm_plantRas5spp, occ = df_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

### RasterStack of models and SpatialPoints of occurrences as Input ###

# Binary Output #

aohmixK_bin <- aohMixK (modSp = sdm_plantSta5spp, occ = Sp_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = FALSE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

# Continuous Output #

aohmixK_con <- aohMixK (modSp = sdm_plantSta5spp, occ = Sp_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

### RasterStack of models and SpatialPoints of occurrences (lista of 'SpatialPoints'
or 'spOcc' class) as Input ###

# Binary Output #

aohmixK_bin <- aohMixK (modSp = sdm_plantSta5spp, occ = sp_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = FALSE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

aohmixK_bin <- aohMixK (modSp = sdm_plantSta5spp, occ = spOcc_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = FALSE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

# Continuous Output #

aohmixK_con <- aohMixK (modSp = sdm_plantSta5spp, occ = Sp_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

#' aohmixK_con <- aohMixK (modSp = sdm_plantSta5spp, occ = spOcc_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = 0.4, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)

### Species-specific threshold for multiple-species ###

# Continuous Output #

aohmixK_con <- aohMixK (modSp = sdm_plantRas5spp, occ = df_plantOcc5spp,
crs = "+proj=longlat +datum=WGS84 +ellps=WGS84 +towgs84=0,0,0", distOcc = NULL,
threshold = plants_thresholds, fraction = 1, partCount = 1, alphaIncrement = 1.0,
buff = 10,  continuous = TRUE, progress = TRUE, removeTempFile = TRUE, saveRas = FALSE,
stack = FALSE, validation = TRUE)