machu.3.anc.niche: Convert ancestral response values to niche models

In wxguillo/machuruku: Ancestral niche reconstruction

Convert ancestral response values to niche models

Description

Create Bioclim niche models for each taxon in each timeslice

Usage

machu.3.anc.niche(
  ace,
  clim,
  taxa = NULL,
  raster.sets = NULL,
  resp.curv = T,
  clip.Q = T,
  clip.amt = 0.95,
  clip.samples = 10000,
  ocean = NA,
  output.folder = NULL,
  verbose = F
)

Arguments

ace	Output of machu.2.ace(). Can be subsetted.
clim	Paleoclimatic data. The best format is SpatRaster from the terra package, or a list of SpatRasters (via the function list()). A group of SpatRasters from multiple timeslices joined with c() is acceptable, but requires the use of raster.sets to differentiate. A RasterStack or list of RasterStacks (via list()) from the raster package is also acceptable.
taxa	Optional, specifies which taxa to run. If the input is not timeslices but tips and nodes (names(ace)=="tips_and_nodes"), 'taxa' can be a numeric or character vector (i.e., 1:3, c(1,4), or c("taxon1", "taxon2")). If the input is timeslices (names(ace)!="tips_and_nodes"), only a character vector can be used. If none of the taxa are present in a given timeslice, that timeslice will be skipped.
raster.sets	Character vector with the names of the various raster sets. Only used if a single raster object containing all paleoclimates is provided for 'clim'.
resp.curv	If TRUE, create ancestral niche models with skew-normal response curves. If FALSE, assume response is a uniform distribution within certain confidence limits specified by 'clip.amt'. This produces a binary niche model. Default = T.
clip.Q	If TRUE, clip the tails of each response curve at certain confidence limits specified by 'clip.amt' (default is 0.95). Produces "cleaner" models. Default = T.
clip.amt	Float value between 0 and 1 specifying confidence limits at which clip.Q=T or resp.curv=F operates. For example, at the default (0.95), the limits are the 0.025% and 0.975% quantiles for each response curve.
clip.samples	The number of random samples taken by rsn() while determining confidence limits when clip.Q=T or resp.curv=F. Default = 10000. Decreasing may result in a speed boost at the cost of accuracy.
ocean	A string or numeric specifying null or "ocean" pixels in the input rasters. Default = NA.
output.folder	A string specifying a folder name to write outputs to. Outputs are only written if this argument is specified. Output will be in .tif format (GeoTiff) and given default names in the format "scenario_taxon.tif".
verbose	If TRUE, print to screen certain checks, statuses, and progress updates. Default = F.

Details

For a single timeslice, the SpatRaster or RasterStack object should have multiple layers, each corresponding to a climate variable. The layers should be consistent in number and type across all timeslices. Within a timeslice, layers should share the same geography (i.e., ocean pixels should be the same).

The function associates timeslices with rasters based on the inputs. When the same number of timeslices and rastersets are provided (length(ace)==length(clim)), the first timeslice will be matched to the first rasterset, and so on. When only one rasterset and multiple timeslices are provided, the timeslices will all be matched to the single rasterset, and vice versa. When 'ace' and 'clim' have different lengths, and lengths > 1, only the first 'x' elements of 'ace' and 'clim' will be used, 'x' being the length of the shorter input, with the first timeslice matched to the first rasterset, and so on. When verbose=TRUE, these rasterset-timeslice associations are printed to the screen.

Whether uncertainty is included in the ancestral niche models depends on the 'ace' input, i.e. whether unc=T was specified in machu.2.ace(). Uncertainty is encoded by the mean, upper confidence limit, and lower confidence limit for each parameter (mean, standard deviation, and skew). When passed to machu.3.anc.niche(), multiple response curves consisting of every combination of these values (n=3^3=27) are used to construct suitabilities for each raster and then summed. This tends to produce much broader (more conservative) models than when unc=F.

When uncertainty is included and resp.curv=F (i.e., binary models are produced), the behavior differs from when uncertainty is not included. A second "clipping" occurs after the multiple suitabilities for that raster (from the 27 combinations of response curve parameters) are summed, because at this point the summed suitability will still not be binary (0 or 1). Suitability values corresponding to raster pixels in the '1-clip.amt' (default=0.05) percentile of suitable values are set to 0, and all values above it are set to 1. This produces a cleaner look more in line with expectations.

You can plot the output models on your own, or use machu.plotmap() to do so.

The output option only outputs tiffs, and constructs automatic filenames using the raster set and taxon for each layer. This may be too limited for your purposes, in which case you should write your own script to output the file types and/or names that you desire for your project.

Value

A list of one element per scenario (timeslice or rasterset), each itself a list of one SpatRaster (ancestral niche model) per taxon.

Examples

## acceptable 'clim' formats
# Single SpatRaster (terra)
clim1 <- c(rast(list.files(rasterfolder, pattern="T1_", full.names=T)))
# List of SpatRasters (preferred)
clim2 <- list(c(rast(list.files(rasterfolder, pattern="T1_", full.names=T))), c(rast(list.files(rasterfolder, pattern="T2_", full.names=T))))
# Multiple rastersets in a single SpatRaster (requires 'raster.sets' be specified)
clim3 <- c(c(rast(list.files(rasterfolder, pattern="T1_", full.names=T))), c(rast(list.files(rasterfolder, pattern="T2_", full.names=T))))
# Single RasterStack (raster)
clim4 <- stack(rast(list.files(rasterfolder, pattern="T1_", full.names=T)))
# List of RasterStacks
clim5 <- list(stack(list.files(rasterfolder, pattern="T1_", full.names=T)), stack(list.files(rasterfolder, pattern="T2_", full.names=T)))

## various 'ace' formats
# Two timeslices, no uncertainty
ace_n <- machu.2.ace(resp, tree, timeslice=c(1e6, 2e6))
# Two timeslices, uncertainty
ace_u <- machu.2.ace(resp, tree, timeslice=c(1e6, 2e6), unc=T)
# No timeslices--only tips and nodes, no uncertainty
ace_t <- machu.2.ace(resp, tree)

## ways of running the actual function
# run with default settings, no uncertainty, two timeslices, two rastersets in SpatRaster format
output.models <- machu.3.anc.niche(ace_n, clim2)
# same as above, but don't clip the models
output.models <- machu.3.anc.niche(ace_n, clim2, clip.Q=F)
# same as above, but produce binary models
output.models <- machu.3.anc.niche(ace_n, clim2, resp.curv=F)
# same as above, but make the binary models more stringent
output.models <- machu.3.anc.niche(ace_n, clim2, resp.curv=F, clip.amt=0.9)
# same as above, but output the models to the present working directory
output.models <- machu.3.anc.niche(ace_n, clim2, resp.curv=F, clip.amt=0.9, output.folder=getwd())

# run with uncertainty (default settings, two timeslices, two rastersets)
output.models <- machu.3.anc.niche(ace_u, clim2)

# run with two timeslices, but project them both into the same single rasterset
output.models <- machu.3.anc.niche(ace_n, clim1)
# run with one timeslice, but project it into two different rastersets
output.models <- machu.3.anc.niche(ace_n[1], clim2)

# run with only certain taxa
output.models <- machu.3.anc.niche(ace_n, clim2, taxa=c("taxon1", "taxon2"))

# run with no actual timeslices, only tips and nodes
output.models <- machu.3.anc.niche(ace_t, clim1)
# same as above, but project all taxa into multiple timeslices
output.models <- machu.3.anc.niche(ace_t, clim2)
# same as above, but only use the first two taxa (both are equivalent)
output.models <- machu.3.anc.niche(ace_t, clim1, taxa=c("taxon1", "taxon2"))
output.models <- machu.3.anc.niche(ace_t, clim1, taxa=1:2)

# plot the first taxon's ancestral niche model from the first timeslice
plot(output.models[[1]][[1]])

wxguillo/machuruku documentation built on Jan. 23, 2025, 3:25 p.m.