nicheROVER (version 1.0)

niche.plot: Plot for 2-d projection of niche regions

Description

For one or more species, creates a series of plots: i) the raw niche indicators (e.g., stable isotope) data, ii) their density estimates, and iii) 2-dimensional projections of probabilistic niche regions based on \(n\)-dimensionsional data.

Usage

niche.plot(niche.par, niche.data, alpha = 0.95, species.names, iso.names, col,
  ndens = 512, pfrac = 0, xlab)

Arguments

niche.par

a list of length nspecies, each element of which in turn is a list with elements mu and Sigma. Each of these will correspond to an ellipse being drawn for that species in the corresponding 2-d plane. See Example.

niche.data

a list of length nspecies, each element of which is a matrix with observations along the rows and niche indicators (e.g., stable isotopes) along the columns.

alpha

size of the niche region to plot. Defaults to 0.95.

species.names

names of the species. Defaults to names(niche.par).

iso.names

names of the niche indicators (or isotopes) to plot. Defaults to colnames(niche.par).

col

vector of colours in which each species will be drawn.

ndens

number of points at which to evaluate kernel density estimates.

pfrac

fraction of the plot on which to display 1-dimensional raw niche indicator data. pfrac = 0 means don't display the raw data in 1-d.

xlab

title of plot, located on the bottom. Defaults to no title.

Value

Returns a series of plots displaying niche indicator data and their probabilistic niche projections.

Details

A set of plots is created for each pairwise combination of niche indicators. Below the diagonal are scatterplots for each species, above the diagonal are ellipses corresponding to 2-d projections of the probabilistic niche regions. The diagonal displays density estimates for each indicator, and optionally the raw 1-d data. See Swanson et al. (2014) for detailed description of the probabilistic niche region.

References

Heidi K. Swanson, Martin Lysy, Ashley D. Stasko, Michael Power, Jim D. Johnson, and James D. Reist (2014). ``What Would Hutchinson Think? A Probabilistic Quantification of Multidimensional Ecological Niches and Niche Overlap''. Ecology: Statistical Reports (accepted).

See Also

overlap.plot, niw.post, niiw.post.

Examples

# NOT RUN {
data(fish) # 4 fish, 3 isotopes

# generate 10 parameter draws from the posteriors of each fish with default prior
nsamples <- 10
fish.par <- tapply(1:nrow(fish), fish$species,
                  function(ii) niw.post(nsamples = nsamples, X = fish[ii,2:4]))

# format data for plotting function
fish.data <- tapply(1:nrow(fish), fish$species, function(ii) X = fish[ii,2:4])

clrs <- c("black", "red", "blue", "orange") # colors for each species
niche.plot(niche.par = fish.par, niche.data = fish.data, pfrac = .1,
          iso.names = expression(delta^{15}*N, delta^{13}*C, delta^{34}*S),
          col = clrs, xlab = expression("Isotope Ratio (\u2030)"))
# }