nicheROVER: niche.plot – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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.

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.

Value

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

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).

Examples

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)"))

nicheROVER

(Niche) (R)egion and Niche (Over)lap Metrics for Multidimensional Ecological Niches

v1.0

GPL-2

Authors

Martin Lysy [aut, cre], Ashley D. Stasko [aut, ctb], Heidi K. Swanson [aut, ctb]

Initial release

2014-07-21