isoAssign: Generate probabilistic isotope assignments

In SMBC-NZP/MigConnectivity: Estimate Migratory Connectivity for Migratory Animals

Generate probabilistic isotope assignments

Description

The isoAssign function generates origin assignments using stable-hydrogen isotopes in tissue. The function generates a probability surface of origin assignment from a vector of stable-isotope values for each animal/sample of interest. Probabilistic assignments are constructed by first converting observed stable-isotope ratios (isoscape) in either precipitation or surface waters into a 'tissuescape' using a user-provided intercept, slope and standard deviation. See Hobson et. al. (2012).

Usage

isoAssign(
  isovalues,
  isoSTD,
  intercept,
  slope,
  odds = 0.67,
  restrict2Likely = TRUE,
  nSamples = NULL,
  sppShapefile = NULL,
  relAbund = NULL,
  isoWeight = NULL,
  abundWeight = NULL,
  population = NULL,
  assignExtent = c(-179, -60, 15, 89),
  element = "Hydrogen",
  surface = FALSE,
  period = "Annual",
  seed = NULL,
  verbose = 1,
  generateSingleCell = FALSE,
  mapDirectory = NULL
)

Arguments

isovalues	vector of tissue isotope values
isoSTD	standard deviation from calibration
intercept	intercept value from calibration
slope	value from calibration
odds	odds ratio to use to set likely and unlikely locations defaults to 0.67
restrict2Likely	if TRUE restricts locations to fall within the 'likely' assignment locations
nSamples	integer specifying how many random samples to draw from a multinomial distribution.
sppShapefile	A polygon spatial layer (sf - MULTIPOLYGON) defining species range. Assignments are restricted to these areas.
relAbund	raster (SpatRast) with relative abundance (must match extent of isotope assignment)
isoWeight	weighting value to apply to isotope assignment
abundWeight	weighting value to apply to relative abundance prior
population	vector identifying location where animal was captured. Same order as isovalues
assignExtent	definition for the extent of the assignment. Can be used in place of sppShapefile to limit assignment. Input should follow c(xmin,xmax,ymin,ymax) in degrees longitude and latitude
element	The elemental isotope of interest. Currently the only elements that are implemented are 'Hydrogen' (default) and 'Oxygen'
surface	DEPRECATED function no longer returns surface water values. Default is 'FALSE' which returns the precipitation isotopes ratio.
period	The time period of interest. If 'Annual' returns a raster of mean annual values in precipitation for the element. If 'GrowingSeason' returns growing season values in precipitation for element of interest
seed	numeric value fed to set.seed for random number generation. Default = NULL
verbose	takes values 0, 1 (default) or 2. 0 prints no output during run. 1 prints a message detailing where in the process the function is. 2 prints the animal currently being sampled.
generateSingleCell	if 'TRUE' generates a single origin location using the posterior assignment distribution - this takes a while to run. If 'FALSE' (default), no coordinates are generated.
mapDirectory	Directory to save/read isotope map from. Can use relative or absolute addressing. The default value (NULL) downloads to a temporary directory, so we strongly recommend changing this from the default unless you're sure you're not going to need these data more than once.

Value

returns an isoAssign object containing the following:

probassign

SpatRast stack of individual probabilistic assignments

oddsassign

SpatRast stack that includes likely vs unlikely origin for each animal

popassign

a SpatRast for population level assignment (sum of oodsassign if population = NULL). If population is a vector then returns a raster stack for each unique population provided

probDF

data.frame of individual probability surfaces

oddsDF

data.frame of likely vs unlikely surfaces

popDF

data.frame of population level assignment

SingeCell

array of coordinates (longitude,latitude) for single cell assignment

targetSites

sf - MULTIPOLYGON layer representing isotope bands equivalent to isoSTD

RandomSeed

the RNG seed used when generating locations from the multinomial distribution

References

Cohen, E. B., C. S. Rushing, F. R. Moore, M. T. Hallworth, J. A. Hostetler, M. Gutierrez Ramirez, and P. P. Marra. 2019. The strength of migratory connectivity for birds en route to breeding through the Gulf of Mexico. Ecography 42: 658-669.

Hobson, K. A., S. L. Van Wilgenburg, L. I. Wassenaar, and K. Larson. 2012. Linking hydrogen isotopes in feathers and precipitation: sources of variance and consequences for assignment to isoscapes. PLoS ONE 7: e35137.

See Also

weightAssign

Examples

extensions <- c("shp", "shx", "dbf", "sbn", "sbx")
tmp <- tempdir()
for (ext in extensions) {
download.file(paste0(
              "https://raw.githubusercontent.com/SMBC-NZP/MigConnectivity",
                     "/master/data-raw/Spatial_Layers/OVENdist.",
                     ext),
              destfile = paste0(tmp, "/OVENdist.", ext), mode = "wb")
}
OVENdist <- sf::st_read(paste0(tmp, "/OVENdist.shp"))
OVENdist <- OVENdist[OVENdist$ORIGIN==2,] # only breeding
sf::st_crs(OVENdist) <- sf::st_crs(4326)

download.file(paste0(
  "https://raw.githubusercontent.com/SMBC-NZP/MigConnectivity",
                     "/master/data-raw/deltaDvalues.csv"),
              destfile = paste0(tmp, "/deltaDvalues.csv"))
OVENvals <- read.csv(paste0(tmp, "/deltaDvalues.csv"))


a <- Sys.time()
b <- isoAssign(isovalues = OVENvals[,2],
              isoSTD = 12,
              intercept = -10,
              slope = 0.8,
              odds = NULL,
              restrict2Likely = TRUE,
              nSamples = 1000,
              sppShapefile = OVENdist,
              assignExtent = c(-179,-60,15,89),
              element = "Hydrogen",
              period = "GrowingSeason") # this setting for demonstration only
Sys.time()-a

SMBC-NZP/MigConnectivity documentation built on March 26, 2024, 4:22 p.m.