QA {assignR}

Quality assessment of geographic assignments

Description

How well does a given isoscape and/or known origin data set constrain the geographic origin of samples? Uses iterative re-sampling of known origin data to evaluate sample assignments and reports a suite of quality metrics.

Usage

QA(known, isoscape, bySite = TRUE, valiStation = 1, valiTime = 50, 
  recal = TRUE, by = 2, prior = NULL, mask = NULL, setSeed = TRUE, 
  name = NULL)

Arguments

known

subOrigData, list of subOrigData, or SpatVector. Known-origin tissue isotope data from the subOrigData function or provided by user. User-provided data must be formatted as subOrigData objects (see subOrigData) or a SpatVector (see Details).

isoscape

SpatRaster with two layers or isoStack object. For user-generated raster objects, the first layer must be the isoscape (mean prediction) and the second the isoscape prediction uncertainty (1 standard deviation).

bySite

logical. Resample known by site (TRUE) or by sample (FALSE)?

valiStation

numeric. How many sites or samples from known are withheld for validation? Must be two or more smaller than the length of known.

valiTime

numeric. How many times do you want to randomly draw validation samples and run the validation? Must be an integer greater than one.

recal

logical. Recalibrate the isoscape(s) using the known-origin data? If FALSE, isoscape should be a calibrated product appropriate to the samples, and a single iteration is run for each sample in known; parameters bySite, valiStation, and valiTime are ignored.

by

integer. Threshold increment to use in evaluating assignment performance. Must be between 1 and 25.

prior

SpatRaster. Optional layer with prior probabilities, which has the same projection, resolution and extent as isoscape.

mask

SpatVector. Constrains the area of the analysis. If this is not provided, the entire area of isoscape is used.

setSeed

logical. Do you want to set.seed() when you randomly draw validation stations? “TRUE” gives the same sequence of random draws each time the function is called.

name

character. Useful for identifying the QA output in subsequent plotting.

Details

If known is a user-provided SpatVector, the first data field must include the measured value for the first (or only) isotope marker and the second the one standard deviation uncertainty on that value. Subsequent fields must include the same information for all other isotope markers included in the analysis, and these markers must appear in the same order as in isoscape. A user-provided SpatVector must include a field named “Site_ID” containing unique values for each sampling site to support the “bySite” option, otherwise use bySite = FALSE.

Value

Returns an object of class “QA”.

val_stations

numeric. An X*Y data.frame of validation station IDs for all valiTime. X = valiTime and Y = valiStation.

pd_val

numeric. An X*Y data.frame containing the posterior probability density for the validation stations. X = valiTime and Y = valiStation.

prption_byArea

numeric. An X*Y data.frame showing the proportion of validation individuals for which the known origin is contained within the top 0.00 to 1.00 area quantile (with increment of by / 100; Y = ceiling(100 / by) + 1). X = valiTime.

prption_byProb

numeric. An X*Y data.frame showing the proportion of validation individuals for which the known origin is contained within the top 0.00 to 1.00 probability quantile (with increment of by / 100; Y = ceiling(100 / by) + 1). X = valiTime.

precision

list. The length of the list is valiTime. Each element is an X*Y matrix showing the proportional area of the total assignment surface covered by the assignment region at a given probability quantile from 0.00 to 1.00 (with increment of by / 100; X = ceiling(100 / by) + 1) for each validation sample (Y = valiStation).

random_prob_density

Random probability of assignment to any given grid cell on the assignment surface(i.e. 1 divided by the total number of grid cells).

name

character. Name assigned to the QA object.

by

integer. Value of by used.

Note

See Ma et al. (2020) for methodological details.

References

Ma, C. et al. (2020) assignR : An R package for isotope-based geographic assignment. Methods in Ecology and Evolution 11 996–1001. doi:10.1111/2041-210X.13426.

Vander Zanden, H. B. et al. (2014) Contrasting assignment of migratory organisms to geographic origins using long-term versus year-specific precipitation isotope maps. Methods in Ecology and Evolution 5 891–900. doi:10.1111/2041-210X.12229

See Also

plot.QA

Examples

# extract some known-origin data
d1 = subOrigData(taxon = "Buteo lagopus")

# run quality assessment based on precipitation hydrogen isotopes and 
# known-origin samples; small values of valiStation and valiTime 
# are used in example to reduce run time

# first with one example
# gives warning because a small number of samples are available
qa1 = QA(known = d1, isoscape = d2h_lrNA, valiTime = 2, by = 10, 
          mask = naMap, name = "Buteo")
                    
# plot the qa result
plot(qa1)

# now compare with a second data set
d2 = subOrigData(taxon = "Charadrius montanus")
qa2 = QA(known = d2, isoscape = d2h_lrNA, valiTime = 2, by = 10, 
          mask = naMap, name = "Charadrius")
plot(qa1, qa2)